Cream of the Crop 22/Cream of the Crop 22.iso/os2/tton1770.zip/docs/README

Text File | 1996-10-20 | 14KB | 310 lines

Templeton version 1.77 Beta
Copyright 1995,1996 N.A. Krawetz
All rights reserved.

Index:
  1. File List
  2. Installation
  3. Configuring
  4. Usage
  5. Application Notes
  6. Disclaimer


1. File List
    INSTALL        this file
    tsolaris    Solaris executable
    tlinux        Linux executable
    templeton.exe    OS/2 executable
    tos2.exe    OS/2 executable (alturnate)
    templeton.cfg    Sample program configuration environment


2. Installation
To install Templeton, place the Templeton executable in a directory
within your path.  No extra libraries or executables should be necessary.
For OS/2, Templeton requires the EMX DLL libraries version 0.9a.  (It should
also work with 0.9b.)  These are available from most OS/2 FTP sites,
including hobbes.nmsu.edu and ftp-os2.cdrom.com.

The templeton.cfg file should be available in the current directory, or
in the directory specified by the ETC or HOME environment variables.


3. Configuring
Edit the templeton.cfg file.  Lines beginning with a '#' are comments and
are ignored.  Lines should not be more than 80 characters.  Operands are in
the form:
    parameter value
The parameter is case insensitive.  Boolean values ("true" or "false") are
case insensitive.  Numeric values should be numbers -- non-numbers are
regarded as 0.  All other types of values ARE case sensitive.

You should set the 'User' parameter to your computer account address.  For
Unix-type systems (Solaris, Linux, etc.) this value is automatically set
to your username@machine_name.  For OS/2 and DOS-bases systems, this defaults
to the set username or "root" at your default IP address (or hostname if
it can be resolved).  If Templeton cannot generate a default 'User' then
the program will display an error message stating that the 'User' must
be set and the program will end.

For networks behind firewalls that must use proxy agents, Templeton supports
'ProxyHost' and 'ProxyPort' configuration parameters.  When using a WWW proxy
agent, you should set the 'ProxyHost' parameter to the hostname of the
proxy agent.  'ProxyPort' should be set to the WWW port on the proxy host.

You may adjust all other configuration options are desired.


4. Usage
To start Templeton, run the executable with the name of the configuration
environment file from the command-line prompt.  In this example, the
executable version in "templeton.exe" for OS/2:
    templeton.exe templeton.cfg

This will start the program and initialize with the current environment
settings.
Multiple configuration environment files may be specified.  If the different
files set the same parameter, then the last parameter setting will be used.
    templeton.exe templeton.cfg templeton.cfg2 templeton.cfg3

System administrators may wish to create a shell script in front of the
executable to always use a specific system-wide configuration, such as setting
the proxy agent.  Unix-based system administrators may store a default
.templetonrc in either /etc/local or /etc.

When the executable is started, it will load in all configuration files.
If multiple configuration files are available, the settings in the last
loaded file are used to overwrite all previous settings.
The files are loaded in the following order:
    /etc/.templetonrc        (Unix and OS/2 only)
    /etc/local/.templetonrc        (Unix and OS/2 only)
    $ETC/{.templetonrc templeton.cfg templeto.cfg}
    $HOME/{.templetonrc templeton.cfg templeto.cfg}
    Current directory: {.templetonrc templeton.cfg templeto.cfg}
    command line parameters

After loading the configuration files, Templeton will prompt the user for
some information:

  Enter starting URL:
The user should enter the starting address of the URL.  This is the WWW
address of the first page to retrieve.  It should be in one of the forms:
    http://host.domain/
    http://host.domain:port/
    http://host.domain/path/
    http://host.domain:port/path/
    http://host.domain/path/file
    http://host.domain:port/path/file
Although the trailing "/" is perfered, it is not (usually) explicitly necessary.

  Enter local path ["none" for log files only]:
The user should specify the directory where the retrieved files should
be stored.  The user should have write permission to this directory and
should verify that it contains enough free storage space to hold the
entire downloaded information.  If you type the word "none" then no
files will be copied; only a mapping log file will be generated in the
current directory.

  Host restriction [yes|no|host|.domain]:
This parameter informs the program not to leave the designated host.
Links to machines not on the current host are not traversed.
Specifying "yes" will restrict to the current host.  "No" will not restrict
to any hosts.  You may also explicitly specify a host name in the form:
    host        (if the machine is local to your subnet)
    host.domain    (if the machine is remote)
For example,
    nestle
    nestle.cs
    nestle.cs.roach.com
If you enter a domain name, starting with the initial "." then
only machines within that domain will be searched.  Examples of value
domain and subdomain names are:
    .edu        (only schools are searched)
    .com        (only companies are searched)
    .uiuc.edu    (only machines at UIUC are searched)
    .cs.tamu.edu    (only the CS department at Texas A&M is searched)

  Should the host's subtree be restricted [yes|no|/path]:
If you are restricting on the current host, then you may also restrict
on a subdirectory on the host.  If you are not restricting on the
host, then you will not see this prompt.
Answering "yes" or "y" will restrict to the directory specified in the
starting URL.  "No" will not restrict the directory.  If you explicitly
enter a path, starting with a "/" then the system will restrict to that
path.  This is useful when the starting URL is not the root of the
desired directory tree.
You should make sure that the starting URL is within the path restriction.

  Enter maximum depth [0 for unlimited]:
Hyperlinks are travered in a breadth-first search.  An unrestricted search
may download an entire WWW server's data.  By restricting the depth,
only immediate portions of the server will be received.  Images and
non-href links are considered to be the same depth as the document.
A restricted depth of 0 means no restriction.

An example response is:
    Enter starting URL: http://www.cs.tamu.edu/people/
    Enter local path ["none" for log files only]: /temp
    Host restriction [yes|no|host|.domain]: yes
    Should the host's subtree be restricted [yes|no|/path]: /people
    Enter maximum depth [0 for unlimited]: 3


Starting the executable with no command-line arguments will display the
usage.

Templeton will generate a number of files.  The files names use the default
index file name (set in the configuration file) [index.html] and the local
saved path (/temp in the above example).
    /temp/mapindex.html    An HTML document showing file links on the
                remote site.
    /temp/locindex.html    An HTML document showing file links in the
                local save-path.
    /temp/host.domain    Directory of files retrieved from the
                machine host.domain
When no local path is specified, only mapindex.html is generated.

While Templeton runs, it displays the current progress:
    Current Depth: 2 (3 max)
    Links at current depth: 7
    Total links remaining:  137

    Current URL: http://www.cs.tamu.edu/people/
    Local file:  /temp/www.cs.tamu.edu/people/index.html
      IMAGE: Images/logos/csimage_basic.gif
      LINK:  Images/index.html
      LINK:  people/index.html

This shows that it is currently at depth 2 out of 3.  There are 7 links
remaining at depth 2, including the current file.  Links include HTML
documents, images, files, and image-maps.  There are currently 137 known links
remaining at all depths.  If the number of links at the current depth is
nearly the same at the total number of links remaining, then there is a good
chance that it is nearly done.  If there is a large difference, then you have
a while to wait.

The status also shows the current URL being processed and the name of the
local file (regardless of whether the local file is being created or just
mapped).  Under the local file are the type and name of all links that are
found.

When all links are processed, the program will end.  You may also break
out of the program at any time.

5. User Interactions
While Templeton is running, the user may perform any of the following
commands:
  l or L    List Restrictions
    Templeton supports robot exclusion.  Typing 'L' shows all known
    exclusion rules.  There are 3 types of rules:
        FORBID: Templeton cannot go there because the server
            explicitly said it could not.
        DENY: Templeton cannot go there.
        ALLOW: Templeton CAN go there.
    The DENY and ALLOW rules may be changed (from DENY to ALLOW, etc.)
    or deleted.  By entering 'A' or 'D' you may explicitly enter a
    URL restriction rule, or you may enter the number of a current
    rule to modify.  Entering 'R' allows you to enter the URL (or number
    of the restriction rule) to remove.  Only DENY and ALLOW rules
    may be modified or removed.

  q or Q    Quit Templeton
  x or X    Exit Templeton

  Any other key will pause the system.  It is not considered "nice" to pause
  the system while it is reading from the remote server since you will be
  pausing a "live" network connection and taking valuable time from the
  remote WWW server.  "Live" connections that are paused for extended
  durations will be closed by the remote server.


6. Application Notes
Templeton attempts to resolve all hostnames.  If a hostname cannot be
resolved, the program may seem to hang (for up to 1 minute).

Please report any errors, problems, or difficulties to [e-mail]
or mail to:    Templeton
        c/o: Neal A. Krawetz
        P.O. Box 345
        Savoy, IL
        USA
        61874-0345

Be sure to include the initial URL, the configuration environment file (for
multiple configuration environment files, you should include the files and
the order in which the files were listed), a description of the error or
difficulty, where it occured (which URL, file, depth, etc.), and the date
and time that you were running the software.


7. Disclaimer

* Software
Templeton is released as shareware and is not free software.  Unregistered
versions of Templeton may not be used for more than 10 minutes at a time.
Templeton may not be used in countries that do not allow crippled or
duration-limited software.

Shareware versions of Templeton may not be distributed to remote FTP or
networked sites without the explicit written permission of the Developer.
Distributed versions of Templeton must contain the entire unmodified
distribution.  The Developer is not responsible for modifications made to
the distribution without the explicit written permission of the Developer.

Registered versions of Templeton may not be distributed in any form for
any reason.

* Use
You, the site or licensed individual, may use one copy of the software product
specified above ("Software") on a single computer.  You may use the Software
on a network provided you have licensed Software equal to the maximum number
of copies in use at one time.  The Software is "in use" on a computer when it
is resident in memory (i.e., RAM) or installed (executable and other files) on
the hard disk or other storage device.  Software installed on a server for
distribution purposes only is not considered "in use."  The Software may not
be used beyond the licensing period.

* Restrictions
You may not alter, merge, modify or adapt this Software in any way including
disassembling or decompiling.  You may not loan, rent, lease, license, or
distribute this Software or any copy.  You may not transfer the Software,
license, documentation, media, or copies.

* Copyright
All intellectual property rights in this Software and user documentation are
owned by N. A. Krawetz ("Developer") and are protected by United States
copyright laws, other applicable copyright laws, and international treaty
provisions.  The Developer retains all rights not expressly granted.

* Limited Warranty
Except as specifically provided herein, the Developer makes no warranty or
representation, promise or guarantee, either express or implied, statutory or
otherwise, with respect to this Software or user documentation, including its
quality, performance, merchantability, or fitness for a particular purpose.

The warranty and remedies set forth herein are exclusive and in lieu of all
other, oral or written, express or implied.  No Software dealer, distributor,
agent or employee is authorized to make any modifications or additions to this
warranty.

* Limitation of Liability
Because software is inherently complex and may not be completely free of
errors, you are advised to verify your work and to make backup copies of your
work.  In no event will the Developer be liable for direct, indirect, special,
incidental, economic, cover, or consequential damages arising out of the use
of or inability to use the Software or user documentation, even if advised of
the possibility of such damages.  In no case shall the Developers' liabilities
exceed the total sum of the Software and licensing agreement.  Some state or
provinces do not allow the exclusion or limitation of implied warranties or
limitation of liability for incidental or consequential damages, so the above
limitations or exclusion may not apply to you.

The Developer is not liable for the usage of the Software. The Developer is
not liable or responsible for information, data, documents, or images
retrieved, generated, stored, copied, or traversed that have copyright or are
proprietary, pornographic, restricted and otherwise illegal.  All ownership
and rights to retrieved, generated, stored, copied, and traversed materials
are retained by their original owners, unless otherwise explicitly stated.